CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / TOOLS / PHELP.ZIP / MANUAL.DOC < prev next >

Wrap

Text File | 1990-12-21 | 46.7 KB | 1,964 lines

THE PINNACLE HELP SYSTEM "The Finishing Touch" Programmer's Manual First Edition P I N N A C L E S O F T W A R E P.O. Box 386, Town of Mount Royal Montreal, Quebec, Canada H3P 3C6 (514) 345-9578 NOTICES This software product is provided "as is" with no guarantees or warranties express or implied. Pinnacle Software and its assigns and subcontractors accept no liability for the use of or inability to use this product, or any damages attributable thereto. This software product is distributed as "shareware". You may try the program out at no charge and distribute complete and unaltered copies for evaluation or use by others. If you are still using it after 30 days, you must pay a licensing fee. The HELPME program itself will provide you with details. The Pinnacle Help System is Copyright (C) 1989 by Pinnacle Software. This manual refers to The Pinnacle Help System as HELPME. This convention must not be construed to lay claim to unique or exclusive use of the name HELPME. Reference to The Pinnacle Help System in any publication must not state or imply otherwise. HELPME was written in Turbo Pascal Version 4, which is a marvelous language product trademarked by Borland International, 4585 Scotts Valley Drive, Scotts Valley, California, USA 95066. HELPME makes use of an outstanding programming toolkit named Technojock's Turbo Toolkit Version 4.0. It is copyrighted by TechnoJock Software Inc. and is available via shareware. Audience This manual is written for programmers and software developers. Upgrades and Support Registered users of this product will be informed of new releases, major bugs, etc. In the past, it has been the policy of Pinnacle Software to offer upgrades at reduced prices. ii TABLE OF CONTENTS NOTICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Audience Upgrades and Support Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 What is HELPME? Why HELPME was Created Who Needs HELPME? Installing HELPME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Sample HELPME; Space-Saving Tip The Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Overview F1 Copyright F2 Introduction F3 User manual F4 Setup and configuration F5 Registration information F6 Registration F7 Customer comment form F8 Changes to this version F9 Files The HLP File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Line 1 -- Product Name Line 2 -- Version Number Line 3 -- Purpose of product Line 4 -- Command-line parameter Line 5 -- Viewer DIR mask Line 6 -- Start-Up Line 7 -- Introduction Line 8 -- Manual Line 9 -- Configuration Line 10 - Customer Comment Form Line 11 - Registration Info Line 12 - Registration Program Line 13 - Exit 14 - 16 - Packager Data Line 17 - Changes This Version ii PDC Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 What is a PDC File? Why Use a PDC File? Advantages for the Programmer; Advantages for the User; The Use of Colour Support for Different Displays Basic PDC Design Control Code Format; PDC File Format; Sample PDC File PDC Files for Display The Customer Comment Form PDC Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Next and Future Versions . . . . . . . . . . . . . . . . . . . . . . . . 20 Towards a Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Looking for Standards A Packaging Standard? Other Pinnacle Products . . . . . . . . . . . . . . . . . . . . . . . . . 24 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 1 Introduction What is HELPME? The Pinnacle Help System equips the software developer with a method of providing new users with the information they need to get started. The Pinnacle Help System is based upon a single program, named HELPME, which can instruct, inform and assist the user in the following general areas: Copyright information Product overview ("What does this program do?") Detailed user manual or (for simpler programs) general usage guide Hardware and software prerequisites Configuration Registration and warranty provisions Program registration (for shareware programs) Correspondance and commentary by mail Files directory File viewing and printing Why HELPME was Created In the vast majority of software products, "first glance" assistance is not provided in a convenient manner. With standard commercial packaging, the user may have to shuffle through several manuals, inserts, blow-ins, response cards and diskettes to find the answers to fundamental questions. In the case of shareware, the user is expected to have an intuitive feel for the operating system and the file-naming conventions that have evolved around the shareware market. Some shareware distributors have pioneered the idea of using the power of the computer to organize "first-timer" information. The solution has generally involved a batch file which calls up Vernon Buerg's excellent LIST program. Such efforts have made life easier for the user. HELPME takes the concept further by simplifying and organizing. HELPME is easy for the user. The user interface is uncomplicated. HELPME is easy for the programmer. The software developer can design a useful, attractive "front-end" to his or her product, with an extremely low investment of effort. 2 Who Needs HELPME? If your software product is not completely self-contained and self- explanatory, you should consider including HELPME in the package. If your software product is extremely complex, or has amazing capabilities that can only be fathomed after months of use, then HELPME can prepare the user in a friendly manner. If you distribute your software via the shareware method, then HELPME can make your product more dynamic and appealing, while addressing the special needs of people who have only recently begun investigating shareware. Companies that distribute software "in-house" should consider using HELPME as a method of introducing their users to new programs. 3 Installing HELPME The HELPME program is completely self-contained in the HELPME.EXE file. Its functions are defined by the .HLP file. When including HELPME with your software (see "NOTICES" for licensing details), all you need to include are the EXE and HLP files, plus any relevant support files you may have written. Sample HELPME For an sample implementation of HELPME, create a directory named HELPME and install the original HELPME package there. This will demonstrate most of the techniques provided by The Pinnacle Help System. Space-Saving Tip To save disk space, you may also wish to put HELPME.EXE in one of your PATH directories. (For an explanation of PATH, see your DOS manual.) This way, all you'll need in each directory are the .HLP file and any support files that you write. However, if you do this, make sure that your final packaging notes remind you to include HELPME.EXE in the final disk or archive file! 4 The Main Menu Overview When somebody starts up your HELPME, he or she sees an introductory screen (if you created one), followed by this menu: F1 Copyright F2 Introduction F3 User manual F4 Setup and configuration F5 Registration information F6 Registration F7 Customer comment form F8 Changes to this version F9 Files Apart from the F1 and F9 options -- which always appear -- the user will see only those options that you have installed. We will now discuss each of the menu options in detail. F1 Copyright This identifies the product, holder of the copyright, mailing address and phone number. Some protection has been built into the program to ensure that some enterprising programmer does not remove the F1 selection or alter the name and address. F2 Introduction The Introduction takes the place of the "READ.ME" file used by many shareware products. It answers the question, "What does this product do?" The Introduction should be very short -- perhaps only one screen in length. Its purpose is to orient the user and give him or her a basic framework for interpreting what will be taught in the user manual. 5 The Introduction may use a program, text or PDC file. See the chapter entitled "The HLP File" for details. F3 User manual F3 enables the user to browse or print the manual-on-disk, which provides the user with detailed instructions for using your product. In most cases, the manual-on-disk will be a standard text file. To accomodate the vast majority of printers, it should be 80 columns or less and use no special control codes except for Form Feed (ASCII 12, Hex 0C). All Word Processing programs have a provision for outputting a document to a text file. F3 may invoke a program, text or PDC file. See "The HLP File" for more information about this flexible technique. F4 Setup and configuration This option is used to define hardware and software resources to your program. In most cases, the F4 key will run a separate program written by the developer. (Writing configuration programs is a dull and thankless chore, so Pinnacle Software is now designing a product named The Pinnacle Configurator, which will enable you to create a configuration program in minutes.) Just like selections F2 to F8, F4 is optional. So if your main program has its own configuration section, you can omit it from HELPME, or have HELPME call a text or PDC file informing the user of this. F5 Registration information Selection F5 covers legal and some marketing information. In this section you can can place: - Disclaimers and limitations of liability - Customer support line phone numbers - Details for registering shareware - Product distribution provisions - Information about discounts for customers You may use a text or PDC file. See "The HLP File" for details. 6 F6 Registration Selection F6 will be used only by shareware developers. It will run a program to register a product. The registration process may stamp a serial number, or remove an opening screen, or enable some features. You will write the actual unlocking program, which obviously must include some programmatic trickery to confound efforts to "crack" it by industrious hackers. Just like selections F2 to F8, F6 is optional. If you do not have a registration program, it will not appear on the menu. F7 Customer comment form This is one of the most convenient features of HELPME. It takes the user through a questionnaire that you design, then prints out the result, along with a mailing envelope that can be assembled with tape or staples. This feature encourages your users to write to you with comments. In this age of telephones, many people strongly dislike spending the time it takes to send a letter. HELPME makes it more likely they will write to you by greatly reducing the effort involved. Selection F7 can invoke a program, text or PDC file. In most cases, it's best to use a PDC file, as this enables you to create the questionnaire in only a few minutes. For more information, see the chapter entitled "PDC Files". F8 Changes to this version This displays a list of enhancements for this version of the program. You may decide to list the enhancements for the last few versions, instead of simply comparing this version with the last one. Remember that some people may not have seen the last version. Perhaps they have the version before that, or an even older version. If it's not too unwieldy, you should list all the enhancements right back to Version 1. This will be helpful to everybody who has ever used your product before, and it will trace the evolution of your product -- many people may find this interesting. 7 F9 Files The Files function displays the current directory and lets the user select a file using the arrow and Enter keys. The selected file is then displayed by the HELPME File Viewer, which provides full browsing with: - Up-arrow and down-arrow - PgUp and PgDn - Find and Find Again - Print file - Jump-to-line-number 8 The HLP File The HELPME.EXE program finds out what to do by inspecting the HLP file. The HLP file is a file with a .HLP extension. If there is more than one HLP file in a directory, the user is instructed to select one. In most cases, this won't happen, because each product will occupy one disk or directory and have only one HLP file. But if the user does install several products into one directory, this won't cause any problems. No confusion will arise if you name your HLP file according to your product name. For example, if your product is named WHIZBANG, you should create a WHIZBANG.HLP file. The HLP file is a standard text file, created with a text editor such as EDLIN, a programmer's editor, or a Word Processor in non-document mode. Each line in the HLP file must start in column one. Any text after column 40 is ignored and may be used for comments. The format of the HLP file is as follows: LINE EXAMPLE DESCRIPTION 1 The WhizBang System Product Name 2 2.00 Version Number 3 Whizzing & Banging Purpose of product 4 /HELP Command-line parameter 5 *.* Viewer directory mark 6 WHIZSTRT Start-up pgm pdc txt 7 WHIZINTR Intro pgm pdc txt 8 WHIZMANU Manual pgm pdc txt 9 WHIZCONF Config pgm pdc txt 10 WHIZCCFM Comment pgm pdc txt 11 WHIZRINF Register pdc txt 12 WHIZRPGM Register pgm 13 WHIZEXIT Exit pgm pdc txt 14 Packager Data #1 15 Packager Data #2 16 Packager Data #3 17 WHIZCHG Changes pgm pdc txt For another example, see the HELPME.HLP file included in the standard HELPME package. Items described as "pgm pdc txt" can invoke a program or display a PDC or text file. (PDC stands for Pinnacle Display Codes -- see "PDC Files" for details.) The name given in the file is used as a root name. If a file in the current directory has the same root name, it might get used. 9 We say it "might" get used because only certain extensions are considered valid. These are: EXE COM PDC TXT DOC ME. Thus, a file named WHIZEXIT.COM would be used, but not a file named WHIZEXIT.DAT. Here is another example. Line 6 of the HLP file defines what will be done when HELPME is started. It can run a program, or display a PDC file or a text file. Let us say that line 6 of the HLP file specified WHIZ. In such case, HELPME would check the directory and behave in the following manner: FILES FOUND IN THE DIRECTORY TYPE OF FILES WHAT IS DONE WHIZ.EXE WHIZ.COM Program files The programs are run WHIZ.PDC PDC files The files are displayed WHIZ.TXT WHIZ.DOC WHIZ.ME Text files The files are displayed When you specify a root name in the HLP file, it doesn't matter if the file is a program or a PDC file or a text file; HELPME behaves appropriately. If it can find a program, it will run it. If it can find a PDC file or a text file, it will display it. We will now discuss the HLP lines in detail. Line 1 -- Product Name This is the proper name of your product. This shouldn't be confused with the program name of your product. For example, your product may be named "The Chocolate Space Warp", while the program is named CSW.EXE. In such case, you should place the full name ("Chocolate Space Warp") here. Line 2 -- Version Number You have up to 40 characters to specify your version number. Most version numbers look something like this: 1.00 2.32A Summer '89 Beta-Test 5.3 10 Line 3 -- Purpose of product This item is not used in Version 1.00 of HELPME, but will be used in Version 2. Describe your product here, in 40 characters or less. Some samples: Word Processing Software Packaging Programming Language Shoot-'Em-Up Game Line 4 -- Command-line parameter When HELPME calls a pgm (COM or EXE) file, it can add a command-line parameter. Thus, the program can find out if it was called from HELPME or from DOS. A command-line parameter is some additional information that is usually passed on the DOS command line. For example, if you type the DOS command DIR you will get a full directory listing. But if you type DIR *.TXT, you are using a command-line parameter to specify that you only want to see files with a TXT extension. Thus, if you have a program which is supposed to be accessed via HELPME, such as a configuration program, and you want to be sure that it is run only by users who have been well-informed, your program can check for the command- line parameter and if it is missing, advise the user to run HELPME. In other words, the command-line parameter can be used to ensure that certain programs can be accessed ONLY through HELPME. The command-line parameters also report what HELPME knows about the display. So if your HLP file specified a command-line parameter of /HELP there would be two possible ways that the program is called: /C /HELP This means the display can show colour /M /HELP This means the display can't show colour (monochrome) Line 5 -- Viewer DIR mask This controls which files will be seen when the user presses F9 (Files) at the main menu of HELPME. In most cases, you can use *.* which means "display all files". However, if you expect your users to be very inexperienced, it might be wise to restrict their ability to view files. With a mask of *.* the user can 11 change directories and get lost, or view program files and become bewildered. Line 6 -- Start-Up This names the file which is used when HELPME starts up. It might be a program that animates an attractive logo, or it might be a PDC or text file that simply says hello to the new user. If you leave the line blank, or specify a nonexistent file, nothing will be done. Line 7 -- Introduction This names the file which gives the product overview. A common choice is READ, in which case the following files could be used: READ.EXE READ.COM READ.PDC READ.TXT READ.DOC and above all READ.ME Traditionally among shareware developers, the READ.ME file introduces the user to the product. Nevertheless, it is advisable to use a different file for the Introduction. Your READ.ME file (if you decide to include one) should start off by saying something like, "For help with this product, enter the HELPME command". Line 8 -- Manual This identifies the file that contains the user manual. In most cases, this will be a text file, such as MANUAL.TXT or MANUAL.DOC. But if your product is very easy to use, you may decide to use a PDC file. And if your product already has a a highly sophisticated, program-driven help system, you may decide to invoke the program itself. In any case, this is another item that is only concerned with the root name. It doesn't matter if it is a program or PDC or text file; HELPME will do whatever is necessary. Line 9 -- Configuration This specifies the root name of the configuration program, or a PDC or text file that describes hardware and software requirements. Just as with all 12 root names in the HLP file, if you do not have anything for this selection, simply leave the line blank and it will not appear on the main menu. Line 10 - Customer Comment Form This names the program, PDC or text file for the Customer Comment Form. In most cases, you'll use a PDC file. See the chapter entitled "PDC Files" for details. Line 11 - Registration Info This will be used mainly by shareware authors. It names a PDC or text file (thought not a program -- see Line 12) to describe to the user the benefits of registering the product. This can include information about upgrades, bonuses, special support and so on. Of course, shareware authors can also use this section to extol the virtues of shareware as a means for keeping down the price of quality software. Line 12 - Registration Program This will be used mainly by shareware authors. It names a program that unlocks the product, usually in conjunction with some kind of password that the user receives when he or she registers. This might include the removal of restrictions or advertising screens, the enabling of advanced features, or simply the stamping of the users' name onto the main program. Line 13 - Exit This names the program, PDC or text file that will be used when the user presses Esc at the Main Menu to return to DOS. In most cases, you will use a PDC file which will describe "What to Do Next", in order to ensure than when the user is presented with the DOS prompt, he or she has a clear idea what command to enter. 14 - 16 - Packager Data These three lines are reserved for the developer. For one reason or another, the developer may decide to use the HLP file to store configuration data. These three lines are ignored by HELPME and may be used to store information. 13 Line 17 - Changes This Version This names a program, PDC or text file that describes any changes to this version. This includes bug-fixes and new features. 14 PDC Files What is a PDC File? A PDC file is a file with an extension of PDC. PDC stands for "Pinnacle Display Codes". PDC files are prepared like standard text files, with DOS's EDLIN, a programmer's editor, or a word-processor in non-document mode. However, PDC files contain special codes which control how the text is displayed by HELPME. Why Use a PDC File? Advantages for the Programmer A PDC file can be created with about the same amount of effort as a word- processing document. Of course, since you will be using your familiar programmer's editor to create the file, you can learn to design PDC files in just a few minutes. The final results are quite attractive, considering the minimal effort required. Advantages for the User Rather than being presented with a drab monochrome listing of a text file, the user controls a colourful "slide show" in which each display page is neatly centered on the screen. By adding a little variety to the displays, and keeping them uncluttered, the programmer can ensure that the user remains visually stimulated. This greatly improves comprehension and retention of the material. The Use of Colour First, a word about spelling. American readers have probably noticed that this manual refers to "colour" rather than "color". We've prepared this manual using Canadian/United Kingdom spelling. However, we've avoided including any debateable spelling in HELPME itself. If you find that an alternate spelling has slipped past us and appears in HELPME, please inform us and we will remove it. Colour is now a very important feature for software. Those of us who spend a lot of time on monochrome screens tend to forget that virtually all software now makes extensive use of colour. However, once you've used a colour screen for a while, you'll become used to seeing it. Programs that don't use colour 15 will strike you as antiquated and unattractive, no matter how many pull-down menus and fancy doo-dads it may otherwise have. The danger is that some people may select an inferior product over yours simply because the other one is more pleasant to look at. Another danger, though, stems from the fact that programmers are not trained to work with colour the way, say, a painter would be. You may have seen programs featuring gaudy screens in which a dozen colours clash, each one clamouring for your attention. HELPME addresses the need for colour, and the method by which we have implemented colour support -- a method intended to promote consistency -- also makes it difficult to overuse colour. Support for Different Displays HELPME (and in particular, PDC file support) supports all standard displays. This includes CGA, EGA (25- or 43-line mode), VGA (25- or 50-line mode), HGC and so on. HELPME is designed to work with monochrome as well as in colour. It does all this without any extra effort by the programmer. Basic PDC Design Overview: This section describes the PDC controls in general terms at an intermediate level of detail. For specific applications, refer to "PDC Files for Display" or "The Customer Comment Form". For examples, refer to the PDC files that accompany the HELPME package. A quick reference guide also appears near the end of this manual. Control Code Format PDC controls start in column one of your PDC file. (The PDC file is created using a standard text editor.) The general format is: /BText or /B Text or /B Text 16 In the first two examples, the text follows immediately after the control code (represented by /B). In the third example, no text follows the control on the same line, so HELPME will look on the next line. This is particularly useful when the control refers to a block of text immediately following. PDC File Format The PDC file format has very few constraints. You must simply ensure that you do not define a page (i.e. screen) that contains more than 25 lines. While HELPME does support screens in 43- and 50-line mode, it does restrict the number of lines per page to 25. Sample PDC File Here is a PDC file that displays two pages. We've placed explanitory comments on the right side of the page, but these would not be included in the file. You will notice that colours are specified by purpose, rather than by name. This helps you ensure consistency in your screens. For a summary of the display codes, refer to the Quick Reference Guide at the end of this manual. /H What is Shareware? <-- Heading colour <-- Skip a line /T <-- Text colour Shareware is "try before you buy" software. <-- Text It lets you see the program and use it for a while. If you like it, you can pay for it. If it turns out it's not appropriate for you, you'll find that out without having to spend any money. <-- Skip a line /E Shareware saves you money! <-- "Effect" colour /P <-- Pause ("Hit spacebar") /H What You Get <-- Heading colour <-- Skip a line /T <-- Text colour If you order now, you get... <-- Text <-- Skip a line /B A SET OF FREE STEAK KNIVES! <-- Bold colour <-- Skip a line /T <-- Text colour So don't delay! Order today! Operators are <-- Text standing by! Call 514-555-5555! /P <-- Final pause (optional) 17 The preceding example would display two pages, each of which are followed by a line saying "Press spacebar to continue...". The text of each page will be neatly centered on the screen, in appropriate colours. HELPME does not right-justify the text. In the example above, the text was justified manually. You may wish to create the initial text with a word- processor, which will justify the text for you. PDC Files for Display PDC files are most commonly used to display succinct information. If you have more than 10 screens worth of information, it might be better to create a text file and advise the user to print out the manual. Display files use all PDC codes except // and /A. The Customer Comment Form The customer comment form (Line 10 of the HLP file) uses the // control code, and /A to prompt for user input. In Version 1 of HELPME, this is the only application of these two controls. The format of the comment form is as follows: 1. The body of letter (Pages defined by: regular PDC text followed by /A) 2. The // control word to mark the end of the questions 3. Your return address For a sample customer comment form, refer to the HELPCCF.PDC file in the standard HELPME package. After the user has filled in all the questions, he or she is advised to make the printer ready. The questionaire, along with a mailing envelope, are then printed. If the user doesn't have a printer, HELPME will simply display the questions without asking the user to type in any answers. The customer comment form is a very powerful concept and has proven helpful to Pinnacle Software. We believe that your company may also find it useful. In-house developers can replace the return address with their Department Number, to encourage feedback from users. 18 PDC Quick Reference For more details, see the chapter entitled "PDC Files". CODE DESCRIPTION /H Heading. See Note 1. /T Regular text. /E "Effect" text. More emphatic than /T text. /B "Bold" text. More emphatic than /E text but less so than /H text. /A Accept a single line of input. See Note 1. /An Accept "n" lines of input. See Note 1. Examples: /A5 /A 05 /P Pause. Displays the page with the notation "Press spacebar to continue". // End of questionnaire. Used before the return address in the customer comment form. NOTE 1: Text is inverse rather than colour-on-black. For monochrome screens, colour-on-black becomes white-on-black, while inverse becomes black-on-white. 19 Next and Future Versions We have not yet scheduled the production of the next version of The Pinnacle Help System, but we do have some ideas. We would also like to hear suggestions from registered users of HELPME. In the meantime, here are some areas of development we are considering... 1. PDC display should use a more aesthetically-oriented algorithm for centering text on the screen. At the moment, the longest line is centered and all others have to comply. This occasionally results in an unattractive screen. 2. Full mouse compatibility for the Main Menu, File Viewer, and so on. A mouse is recognized by Version 1 in a few instances, but not enough to make it truly "mouse compatible". 3. The answer to the "Colour?" question could be saved in HELPME.SYS file in root directory. See the chapter entitled "Towards a Standard" for a relevant commentary. 4. Allow the programmer to assign descriptions and functions to the FKeys. Version 1.00 of HELPME is not very flexible in this regard; your only option is to omit options. 5. The Pinnacle Configurator. This will enable the programmer to specify what items need to be configured, along with explanatory text. Our goal is to make it very easy to create such a facility. For an early example of our direction in this regard, refer to the configuration programs for Pinnacle's Sapphire and Pyroto products. We have more sophisticated versions in our workshop, which are more closely related to HELPME, but these have not yet been released, and they are not yet generic. However, considering the hundreds of man-years that could be saved by a generic configurator, we should certainly pursue this project. The success (i.e. number of registrations) for HELPME will determine our schedule in this regard. 6. New PDC commands. We've already developed some extensions to the PDC codes but these have not been implemented in Version 1.00 of HELPME. Some ideas that might prove applicable include: /Fx Force the next x lines to the top of the screen The remaining lines are centered in the remaining space /X Put a box around the screen /Q Display text and continue (used for Exit screen) 20 7. Full 43- and 50-line compatibility for the File Viewer. At the moment, the File Viewer acts as a sort of "top-of-the-screen window" when called in 43- or 50-line mode. This does not take full advantage of these modes. 8. Release some HELPME modules as Turbo Pascal toolkits. Our SHOWVIEW (File Viewer) and PAGE (PDC Processor) units could prove helpful to Turbo Pascal programmers. We will rely upon the comments of registered HELPME users to guide us in making our decision in this regard. 21 Towards a Standard This chapter is directed towards shareware authors. Looking for Standards Standards are hard to come by. True, there exist organizations such as CCITT or ANSI, whose serve to recommend the "usual" way of doing things. But in the PC world, a lot of important development takes places informally, far beneath the notice of such august organizations. The shareware market is a good example. An astonishing amount of high-quality software has been produced by the "electronic cottage industry". Yet apart from efforts by groups such as the Association of Shareware Professionals, aided by a few forward-looking shareware distributors, we haven't seen much standardization in the presentation of this kind of software. Standardization eludes us. It taunts us, always staying just out of reach. For example, we might think that it's now obvious that each shareware package should contain a file named READ.ME which is the first thing somebody should check after getting their hands on some new software. However, some developers don't think READ.ME is the right name for such a file. Here are some quite defensible alternate names that have appeared recently: README. README.EXE README.BAT README.1ST README.NOW INFORMAT.ION Of course, two of those files aren't even text files. But aren't programs far more convenient? Of course, in that case, the suggested name is hardly appropriate. Perhaps they should be called "RUNFIRST"? And even if we could decide what to call the darn thing, what would it describe? Is it truly an introduction to the product (in which case, it might be named README.1ST), or is it simply a last-minute bug report? Commercial products especially use READ.ME files in this role. 22 A Packaging Standard? This brings us to our admittedly self-serving conclusion. We have been issuing and downloading shareware products for a few years, now. And we've seen wide variety in the quality of packaging. Because we wanted to improve the overall appearance of our shareware without constantly "reinventing the wheel", we created HELPME. It enabled us to repackage a portion of the Pinnacle Software catalog in a standard way, and it helped make these products more "welcoming" to the user. We have no doubt that there are programmers out there who could write faster versions of the program, yet we'd still like to propose that some of us work towards making this a standard method of presenting our wares. We set the HELPME licensing fee at about two hours' worth of time for an average computer consultant. Since the average shareware author is hardly average in any other way, we figured that HELPME would thus be priced reasonably. We would welcome suggestions from anybody on the subject of shareware standardization, and what part we can play in it. We believe that HELPME can go a long way towards making shareware more friendly, but we're sure that it can be improved. So we count on your feedback and your participation, which are, after all, the very foundations of shareware. 23 Other Pinnacle Products Here are some other Pinnacle Software products. The ones marked with an asterisk (*) use HELPME or an early version of the product. Most of these products are available through CompuServe, major shareware distributors and our North American Software Distribution BBS's. SAPPHIRE * The Original Zero-Maintenance BBS PYROTO * The Original BBS/Gaming System VARITALE * The multi-path, multi-authoring-by-modem system SBD The Super Booking Database for seminars and performances HLRB * Create Handy Little Reference Books that fit in your wallet LOVEFIRE * An adventure game that's a parody of a romance novel PINNTALE A compiler for writing interactive stories LW * Label printer designed for people who've never computed before MEGADIII A stupid game that only a true programmer could appreciate PHONEMEM Techniques for memorizing phone and other numbers PINNARTX Amazing PC artwork for any display -- even monochrome PRESERVE A handy alternative to the BACKUP command SECURE A bogus security system that just might save your valuables SPACEINV Arcade game for monochrome displays SV Experiment with the modes of your video card WEED A text-file cleaner-upper -- ideal for BBS logs DECISION Amusing executive decision-maker SFBI * The "Star Fleet Battles" gaming assistant All of these programs (except SBD) may be obtained as shareware for only $15 when you register your copy of HELPME. 24 INDEX Can't find it here? Check the Table of Contents. // 18, 19 File Viewer 20, 21 /A 18, 19 Files 2 /B 19 /E 19 Guarantees ii /H 19 /P 19 Hackers 7 /T 19 Heading 19 43-line 16, 17, 21 HELP ii 50-line 16, 17, 21 HELPCCF.PDC 18 HGC 16 ANSI 22 HLP 4, 9 HLRB 24 Bold text 19 Borland ii Installation 4 Buerg 2 Inverse 19 Canadian 15 Justified 18 CCITT 22 Centering 20 Licensing ii CGA 16 Limitations of liability 6 Changes This Version 14 LIST 2 Color 15 LOVEFIRE 24 Colour 15 LW 24 Command-line parameter 11 Comment Form 13, 18 Manual 2 Configuration 2, 6, 12 Mask 11 Configurator 20 MEGADIII 24 Consistency 17 Monochrome 16, 19 Control code 17 Mouse 20 Control Code Format 16 Copyright ii Non-document mode 15 Correspondance 2 Crippleware 13 Overview 2 DECISION 24 Disclaimers 6 Display Codes 15 Displays 16 Doo-dads 16 EDLIN 15 Effect text 19 EGA 16 Envelope 18 Examples 4 25 Packager Data 13 Page 17, 21 User input 18 PATH 4 User manual 2 Pause 19 Pdc 9, 15 VARITALE 24 PDC commands Versions ii, 20 New 20 VGA 16 PDC Processor 21 Pgm 9, 11 Warranties ii PHONEMEM 24 WEED 24 Pinnacle Display Codes 15 What to Do Next 13 PINNARTX 24 Whiz 9 PINNTALE 24 PRESERVE 24 Press spacebar 18 Printer 18 PYROTO 24 Questionaire 18 Questions 18 READ.ME 5, 12 Registration 2, 13 Return address 18 Right-justify 18 Root 9 SAPPHIRE 24 SBD 24 SECURE 24 SFBI 24 Shareware ii, 22, 24 Shareware authors 13 SHOWVIEW 21 Slide show 15 Spacebar 18 SPACEINV 24 Spelling 15 Standards 22 Steak Knives 17 SV 24 TechnoJock ii Text files 15 Txt 9 26 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 2,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.